<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<title>VMware Command Line Tools</title>
</head>
<body>
<a name="top"><h1>VMware Command Line Tools</h1></a>
<p>[Introduction]
[<a href="#details">Details</a>]
[<a href="#build">Build Notes</a>]

<h2>Introduction</h2>

<p><strong>NOTE: Most functions of these programs are now covered by
&quot;vmw.exe&quot; for Windows and &quot;vmw.com&quot;, &quot;vmtsr.com&quot;
for DOS (<a href="http://chitchat.at.infoseek.co.jp/vmware/vmtools.html"
>http://chitchat.at.infoseek.co.jp/vmware/vmtools.html</a>).
Also some of these programs may not work or may behave differently
on recent VMware products, since they were developed on VMware Workstation 3.x
and have not been updated afterwards.
</strong></p>

<p>VMware Command Line Tools is a set of several small and simple command line
programs for DOS and Windows to use VMware's undocumented &quot;backdoor&quot;
functions.  It consists of the following programs:</p>

<table border="1" cellpadding="5">
	<tr>
		<th>name</th>
		<th>description</th>
	</tr>
	<tr>
		<td><a href="#vmchk">vmchk</a></td>
		<td>Checks if it is running inside VMware.<br>
	</tr>
	<tr>
		<td><a href="#vmdev">vmdev</a></td>
		<td>Connects and disconnects connectable virtual devices,
			 such as floppy, CD, sound and NIC.</td>
	</tr>
	<tr>
		<td><a href="#vmpref">vmpref</a></td>
		<td>Enables and disables VMware GUI preference settings,
			such as copy &amp; paste and time synchronization.</td>
	</tr>
	<tr>
		<td><a href="#vmtime">vmtime</a></td>
		<td>Synchronizes guest's system time with host's system time.<br>
			Note that this is just a regular &quot;one shot&quot; program and
			you have to run it periodically to keep guest and host in sync for
			a long period of time.</td>
	</tr>
	<tr>
		<td><a href="#vmcopy">vmcopy</a></td>
		<td>Copies text data from guest to host's clipboard.<br>
			Since DOS doesn't have any built-in clipboard,
			it reads text from standard input.<br>
		</td>
	</tr>
	<tr>
		<td><a href="#vmscr">vmscr</a></td>
		<td>Like vmcopy, this program copies text data from guest to host
			but it reads text from screen instead of standard input.<br>
			In short, you can take a &quot;screen shot&quot; of DOS guest.<br>
		</td>
	</tr>
	<tr>
		<td><a href="#vmpaste">vmpaste</a></td>
		<td>Pastes text data from host's clipboard to guest.<br>
			Since DOS doesn't have any built-in clipboard,
			it writes text to standard output.</td>
	</tr>
	<tr>
		<td><a href="#vmpop">vmpop</a></td>
		<td>Well, it's a kind of joke...</td>
	</tr>
</table>
<div align="right"><a href="#top">TOP</a></div>
<hr>

<h2><a name="details">Details</a></h2>

<h3><a name="vmchk">vmchk.com (DOS16)<br>vmchk.exe (WIN32)</a></h3>

<p>Checks if it is running inside VMware and output the result to standard
output.  Also returns the result as return status (ERRORLEVEL) so you can
use it in DOS batch files.
If you don't want it to print to screen (for example, when using in a batch
file), simply redirect the output to NUL device.</p>

<p>When outside VMware (i.e. in real machine), return status is 0.<br>
When inside VMware, return status is &quot;version number&quot;
returned by VMware.<br>
What this &quot;version number &quot; means is anyone's guess.</p>

<p><strong>Options:</strong><br>
None.</p>

<p><strong>Examples:</strong><br>

When outside VM
<pre>    C:\>vmchk
    Not running inside VMware.</pre>

When inside VM
<pre>    C:\>vmchk
    Running inside VMware (version 6).</pre>

A batch file example
<pre>
    @echo off
    vmchk > NUL

    if errorlevel 1 goto inside

    echo Not in VM!
    ...

    :inside
    echo Inside VM!
    ...
</pre>
<div align="right"><a href="#top">TOP</a></div>
<hr>

<h3><a name="vmdev">vmdev.com (DOS16)<br>vmdev.exe (WIN32)</a></h3>
<p>Connects and disconnects devices.  Also prints current device state to
standard output.</p>
<p><strong>Options:</strong><br>
vmdev [&lt;action&gt;][&lt;device&gt;]</p>
<table cellpadding="3">
	<tr>
		<td colspan="2">&lt;action&gt;</td>
	</tr>
	<tr>
		<td align = "center" valign="top">+</td>
		<td>Connect target device(s). This is the default.<br>
				When the target device is already connected, this option causes
				it to be disconnected and reconnected.
				<font size="1">(Well, I'm a bit proud of this feature.
				 It's convenient. Honest!)</font></td>
	</tr>
	<tr>
		<td align="center" valign="top">-</td>
		<td>Disconnect target device(s).</td>
	</tr>
	<tr>
		<td colspan="2">&lt;device&gt;</td>
	</tr>
	<tr>
		<td align = "center" valign = "top">0..9</td>
		<td>Target device number to connect / disconnect.</td>
	</tr>
	<tr>
		<td align = "center" valign = "top">*</td>
			<td>Represents all devices present.  This is the default.</td>
	</tr>
</table>
<p>When both &lt;action&gt; and &lt;device&gt; options are omitted,
it only shows current device state list.  Connected devices are marked
with '+' in the list.
</p>

<p><strong>Examples:</strong><br>
To print current device state list:
<pre>    vmdev</pre>
To connect (or reconnect) all devices:
<pre>    vmdev *
 or vmdev +*
 or vmdev +</pre>
Likewise, to disconnect all devices:
<pre>    vmdev -*
 or vmdev -</pre>
To connect (or reconnect) device number 2:
<pre>    vmdev 2
 or vmdev +2</pre>
To disconnect device number 1.
<pre>    vmdev -1</pre>
</p>
</p>
<div align="right"><a href="#top">TOP</a></div>
<hr>

<h3><a name="vmpref">vmpref.com (DOS16)<br>vmpref.exe (WIN32)</a></h3>
<p>Enables and disables following preference settings.  Also prints current
setting list to standard output.
<ul>
	<li>Grab when cursor enters window.</li>
	<li>Ungrab when cursor leaves window.</li>
	<li>Scroll when cursor approaches window edge.</li>
	<li>Copy and paste between host and guest.</li>
	<li>Time synchronization between host and guest.</li>
</ul>
First three features concerning mouse movement are useless for
DOS guests anyway, because I'm yet to figure out how to grab /
release mouse cursor from a program.<br>
Time synchronization also is irrelevant for DOS guests because
VMware Command Line Tools doesn't rely on this setting.<br>
However, copy and paste setting does affect VMware Command Line Tools.
VMware simply doesn't allow data transfer when this
feature is disabled.</p>
<p><strong>Options:</strong><br>
vmpref [[&lt;action&gt;]&lt;feature&gt;]</p>
<table cellpadding="3">
	<tr>
		<td>&lt;action&gt;</td>
		<td></td>
	</tr>
	<tr>
		<td align = "center" valign="top">+</td>
		<td>Enables specified feature.</td>
	</tr>
	<tr>
		<td align="center" valign="top">-</td>
		<td>Disables specified feature.</td>
	</tr>
	<tr>
		<td>
		<td>When &lt;action&gt; option is omitted, the default action
			is to 'toggle' current setting.</td>
	<tr>
		<td>&lt;feature&gt;</td><td></td>
	</tr>
	<tr>
		<td align = "center" valign = "top">G</td>
		<td>Grab when cursor enters window.</td>
	</tr>
	<tr>
		<td align = "center" valign = "top">U</td>
		<td>Ungrab when cursor leaves window.</td>
	</tr>
	<tr>
		<td align = "center" valign = "top">S</td>
		<td>Scroll when cursor approaches window edge.</td>
	</tr>
	<tr>
		<td align = "center" valign = "top">C</td>
		<td>Copy and paste between host and guest.</td>
	</tr>
	<tr>
		<td align = "center" valign = "top">T</td>
			<td>Time synchronization between host and guest.</td>
	</tr>
</table>
<p>&lt;feature&gt; options are case insensitive. When &lt;feature&gt;
options is omitted, it only shows current preference setting list.
</p>

<p><strong>Examples:</strong><br>
To print current preference setting:
<pre>    vmpref
 or vmpref +
 or vmpref -</pre>
To toggle 'copy and paste' feature:
<pre>    vmpref c</pre>
To enable 'time synchronization' feature:
<pre>    vmdev +t</pre>
To disable 'ungrab' feature:
<pre>    vmdev -u</pre>
</p>
<div align="right"><a href="#top">TOP</a></div>
<hr>

<h3><a name="vmtime">vmtime.com (DOS16)<br>vmtime.exe (WIN32)</a></h3>
<p>Synchronizes guest's clock to host's clock, when executed.
Also prints updated current time to standard output.
It is not capable of running background so you have to
run it periodically to have host and guest in sync for a long
period of time. Consider using vmw.exe for Windows guest and
vmtsr.com for DOS guest for that purpose.</p>

<p><strong>Options:</strong><br>
None
</p>

<div align="right"><a href="#top">TOP</a></div>
<hr>

<h3><a name="vmcopy">vmcopy.com (DOS16)<br>vmcopy.exe (WIN32)</a></h3>
<p>Reads text data from standard input and copy it to host's clipboard.<br>
Although both versions read text from standard input, DOS16 version does not
accept keyboard input (actually it does, but it never waits for input so
unless you can type <i>very</i> fast it quits before you type anything).
This program is intended to be used with pipe and/or redirection.</p>
<p>WIN32 version can send maximum of 65,355 bytes, which I believe to be a
limitation imposed by VMware. DOS16 version can handle slightly less,
somewhere around 65,000 bytes.</p>
<p>Just like official VMware-Tools, only text data can be transferred.
This is, as it turned out, because VMware performs LF - CR/LF conversion
unconditionally.</p>
<p>For this program to work,  VMware's copy &amp; paste feature must be
enabled.  VMware simply doesn't pass any data when it is disabled.
And here's a catch. When you use this (either DOS16 or WIN32 version)
in Windows guest with official VMware-Tools running, <strong>you must disable
the copy &amp; paste feature after you sent data to host</strong>.
Otherwise official VMware-Tools overwrites host's clipboard when you release
cursor from guest (with text stored in guest's clipboard), so you can never
retrieve the text you sent from guest.<br>
<a name = "copyeg">You can</a> automate it with a simple batch file, if you like:
<pre>    @echo off
    REM ensure that copy &amp; paste is enabled
    vmpref +c

    REM copy data from stdin
    vmcopy

    REM now disable copy &amp; paste
    vmpref -c</pre>
<p><strong>Options:</strong><br>
None.

<p><strong>Examples:</strong><br>
To copy text from a file:
<pre>    vmcopy &lt; somefile.txt</pre>

To copy result of a command:
<pre>    dir | vmcopy</pre>

<div align="right"><a href="#top">TOP</a></div>
<hr>

<h3><a name="vmscr">vmscr.com (DOS16)</a></h3>
<p>Reads text data from screen and copy it to host's clipboard.<br>
There is no WIN32 version because it would be just plain useless.
Use official VMware-Tools instead.
</p>

<p>NOTE: vmtsr.com for DOS now provides the same function with a hot key
combination support (you can take snapshot almost any time).

<p>In the same way as <a href="#vmcopy">vmcopy</a>, this program needs
that VMware's copy &amp; paste feature enabled because
VMware doesn't pass any data when it is disabled.<br>
And be careful when you use it in Windows guest with official VMware-Tools
running, <strong>you must disable the copy &amp; paste feature after you
sent data to host</strong>.
Otherwise official VMware-Tools overwrites host's clipboard when you release
cursor from guest (with text stored in guest's clipboard), so you can never
retrieve the text you sent from guest.<br>
You can automate it with a simple batch file:
<pre>    @echo off
    REM ensure that copy &amp; paste is enabled
    vmpref +c

    REM copy data from stdin
    vmscr

    REM now disable copy &amp; paste
    vmpref -c</pre>
</p>

<p><strong>Options:</strong><br>
None.

<p><strong>Examples:</strong><br>
When combined with <a href="#vmpaste">vmpaste</a> you can take a
&quot;screen shot&quot; of DOS guest within the guest alone, 
borrowing host's clipboard.
<pre>    vmscr
    vmpaste > screen.txt</pre>
</p>

<div align="right"><a href="#top">TOP</a></div>
<hr>

<h3><a name="vmpaste">vmpaste.com (DOS16)<br>vmpaste.exe (WIN32)</a></h3>
<p>Reads text data from host's clipboard and write it to standard output.<br>
Like <a href="#vmcopy">vmcopy</a>, it is intended to be used with pipe
and/or redirection.
</p>

<p>VMware passes 65,355 bytes at maximum, and both DOS16 and WIN32
versions can handle that much.
When host's clipboard holds larger data than that, VMware doesn't pass
any data to guest.
</p>

<p>VMware's copy &amp; paste feature must be enabled for this program to work.
Other precautions mentioned in <a href="#vmcopy">vmcopy</a> section
are not necessary.
</p>

<p>Unlike other VMTools Command Line Tools programs, this program writes
error message to standard error (WIN32) or directly to screen (DOS16) because
standard output is likely to be redirected.</p>

<p><strong>Options:</strong><br>
None.</p>

<p><strong>Examples:</strong><br>
To save text from host's clipboard to a file:
<pre>    vmpaste > somefile.txt</pre>

To send text from host's clipboard to other program:
<pre>    vmpaste | sort > sorted.txt</pre>

<div align="right"><a href="#top">TOP</a></div>
<hr>

<h3><a name="vmpop">vmpop.com (DOS16)<br>vmpop.exe (WIN32)</a></h3>
<p>This program causes VMware to popup the
<pre>    A bootable CD-ROM disc, floppy diskette,
    or hard disk was not detected.</pre>
dialog in the host.  I have no idea how this can be useful for
anyone, but I've included this anyway for the sake of itself.<br>
One thing I believe to be worth mentioning is that a virtual machine
is completely frozen until you click 'OK' button in the dialog.
Maybe someone imaginative enough can think out some practical use of it.<br>
<p><strong>Options:</strong><br>
None.

<div align="right"><a href="#top">TOP</a></div>
<hr>
<h2><a name="build">Build Notes</a></h3>
<p>Here are some notes about compiling/assembling VMware Command Line Tools
from source files.  Mostly it should be pretty straight forward if you have
ever written a program yourself.
</p>

<p><strong>About C source files (WIN32)</strong>
<ul>
	<li>Executables in download package are build with
		<a href="http://www.digitalmars.com/">Digital Mars
		Free C/C++ Compiler</a> only because it generates smaller
		executables than Microsoft Visual C++.<br>
		You can compile them with MSVC without any modification.<br>
		You may have to edit inline assembly parts to compile them with
		different compilers.</li>
	<li>You can build DOS16 executables from the same source files
		if the compiler/linker supports it (Digital Mars' compiler does).
		In fact before I decided to write DOS16 version in assembly
		language, both WIN32 and DOS16 versions shared the same sources.</li>
</ul>
</p>

<p><strong>About assembly source files (DOS16)</strong>
<ul>
	<li>They use a lot of MASM 6 specific directives and pseudo-codes so
		you may not be able to build them with other assemblers.</li>
	<li>Segment registers handling is completely omitted from all sources.
		Be sure to choose DOS tiny memory model when linking them.</li>
</ul>
</p>

<div align="right"><a href="#top">TOP</a></div>
<hr>
</body>
</html>
